<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.29
     from novice.tnf on 19 December 2010 -->

<TITLE>Guide for New Eli Users - Example of Eli Use</TITLE>
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000" BACKGROUND="gifs/bg.gif">
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0" VALIGN=BOTTOM>
<TR VALIGN=BOTTOM>
<TD WIDTH="160" VALIGN=BOTTOM>
<A HREF="http://eli-project.sourceforge.net/">
<IMG SRC="gifs/elilogo.gif" BORDER=0>
</A>&nbsp;
</TD>
<TD WIDTH="25" VALIGN=BOTTOM>
<img src="gifs/empty.gif" WIDTH=25 HEIGHT=25>
</TD>
<TD ALIGN=LEFT WIDTH="475" VALIGN=BOTTOM>
<A HREF="index.html"><IMG SRC="gifs/title.png" BORDER=0></A>
</TD>
<!-- |DELETE FOR SOURCEFORGE LOGO|
<TD>
<a href="http://sourceforge.net/projects/eli-project">
<img
  src="http://sflogo.sourceforge.net/sflogo.php?group_id=70447&amp;type=13"
  width="120" height="30"
  alt="Get Eli: Translator Construction Made Easy at SourceForge.net.
    Fast, secure and Free Open Source software downloads"/>
</a>
</TD>
|DELETE FOR SOURCEFORGE LOGO| -->
</TR>
</TABLE>

<HR size=1 noshade width=785 align=left>
<TABLE BORDER=0 CELLSPACING=2 CELLPADDING=0>
<TR>
<TD VALIGN=TOP WIDTH="160">
<h4>General Information</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="index.html">Eli: Translator Construction Made Easy</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gindex_1.html#SEC1">Global Index</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="faq_toc.html" >Frequently Asked Questions</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Tutorials</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="EliRefCard_toc.html">Quick Reference Card</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="novice_toc.html">Guide For new Eli Users</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="news_toc.html">Release Notes of Eli</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="nametutorial_toc.html">Tutorial on Name Analysis</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="typetutorial_toc.html">Tutorial on Type Analysis</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Reference Manuals</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ui_toc.html">User Interface</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="pp_toc.html">Eli products and parameters</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lidoref_toc.html">LIDO Reference Manual</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ee.html" >Typical Eli Usage Errors</a> </td></tr>
</table>

<h4>Libraries</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lib_toc.html">Eli library routines</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="modlib_toc.html">Specification Module Library</a></td></tr>
</table>

<h4>Translation Tasks</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lex_toc.html">Lexical analysis specification</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="syntax_toc.html">Syntactic Analysis Manual</a></td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="comptrees_toc.html">Computation in Trees</a></td></tr>
</table>

<h4>Tools</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="lcl_toc.html">LIGA Control Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="show_toc.html">Debugging Information for LIDO</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="gorto_toc.html">Graphical ORder TOol</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="fw_toc.html">FunnelWeb User's Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="ptg_toc.html">Pattern-based Text Generator</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="deftbl_toc.html">Property Definition Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="oil_toc.html">Operator Identification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="tp_toc.html">Tree Grammar Specification Language</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="clp_toc.html">Command Line Processing</a> </td></tr>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="cola_toc.html">COLA Options Reference Manual</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="idem_toc.html">Generating Unparsing Code</a> </td></tr>
</table>
<p>
<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="mon_toc.html">Monitoring a Processor's Execution</a> </td></tr>
</table>

<h4>Administration</h4>

<table BORDER=0 CELLSPACING=0 CELLPADDING=0>
<tr valign=top><td><img src="gifs/gelbekugel.gif" WIDTH=7 HEIGHT=7 ALT=" o"> </td><td><a href="sysadmin_toc.html">System Administration Guide</a> </td></tr>
</table>

<HR WIDTH="100%">
<A HREF="mailto:eli-project-users@lists.sourceforge.net">
<IMG SRC="gifs/button_mail.gif" BORDER=0 ALIGN="left"></A>
<A HREF="index.html"><IMG SRC="gifs/home.gif" BORDER=0 ALIGN="right"></A>

</TD>
<TD VALIGN=TOP WIDTH="25"><img src="gifs/empty.gif" WIDTH=25 HEIGHT=25></TD>

<TD VALIGN=TOP WIDTH="600">
<H1>Guide for New Eli Users</H1>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="novice_1.html"><IMG SRC="gifs/prev.gif" ALT="Previous Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="novice_3.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="novice_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
<H1><A NAME="SEC7" HREF="novice_toc.html#SEC7">Example of Eli Use</A></H1>
<P>
The example in this chapter illustrates how text processors are specified
to Eli.
Each section covers a major step in the development process,
<A NAME="IDX150"></A>
discussing the purpose of that step and then carrying it out for the example.
A set of exercises is provided with each section.
The purpose of these exercises is to familiarize you with the basic
facilities that Eli provides for dealing with specifications, and how Eli
is typically used.
<A NAME="IDX152"></A>
<A NAME="IDX151"></A>
<P>
All of the text used in the exercises can be obtained, and the exercises
themselves can be carried out, using the facilities of Eli's
system documentation browser described in the first set of exercises given
below (see  <A HREF="novice_2.html#SEC9">Exercises</A>).
<P>
<H2><A NAME="SEC8" HREF="novice_toc.html#SEC8">Statement of the problem to be solved</A></H2>
<P>
You need to classify a collection of several thousand words.
There are no duplicate words in any class, but a given word may belong to
more than one class.
The classes have arbitrary names, and no two classes may have the same
name.
<P>
A C program will manipulate the words and classes.
Because of the application, classes will be relatively fluid.
The customer expects that new words and classes will be added,
and the classification of existing words changed,
on the basis of experience and changing requirements.
Nevertheless, the system design requires that the data be built into the C
program at compile time.
<P>
The system designers have settled on an internal representation of the data
involving an array for each class containing the words in that class as
strings, an array containing the class names as strings, and an array
containing the sizes of the classes as integers.
The number of classes is also given.
All of these data items are to be specified in a single header file.
Here is an example of such a header file for a simple classification:
<P>
<PRE>
int number_of_sets = 3;

char *name_of_set[] = {
"colors",
"bugs",
"verbs"};

int size_of_set[] = {
3,
5,
4};

char *set_of_colors[] = {
"red",
"blue",
"green"};

char *set_of_bugs[] = {
"ant",
"spider",
"fly",
"moth",
"bee"};

char *set_of_verbs[] = {
"crawl",
"walk",
"run",
"fly"};

char **values_of_set[] = {
set_of_colors,
set_of_bugs,
set_of_verbs};
</PRE>
<P>
Although the meaning of the internal representation is straightforward, it
is quite clear that making the necessary alterations will be a tedious and
error-prone process.
Any change requires compatible modifications of several arrays.
For example, moving a word from one class to another means not only cutting
and pasting the word itself, but also changing the sizes of both classes.
<P>
It would be simpler and safer to define the classification with a notation
ideally suited to that task, and generate the header file from that
definition.
Here is an example of an obvious notation, defining the classification
represented by the header file given above:
<P>
<PRE>
colors{red blue green}
bugs{ant spider fly moth bee}
verbs{crawl walk run fly}
</PRE>
<P>
The remainder of this chapter discusses the specification and generation of
a program that translates class descriptions into header files.
This program must accept a class description, verify that class names are
unique and that there is only one occurrence of any given word in a class,
and then write a header file defining the appropriate data structure.
Its specification is broken into four parts, each stored in a separate
file:
<P>
<DL COMPACT>
<DT><TT>`sets.con'</TT>
<DD>A context-free grammar describing the structure of the input text.
<P>
<DT><TT>`word.gla'</TT>
<DD>A specification of the character sequences that are acceptable words,
and how those character sequences should be represented internally,
plus a specification of the character sequences to be ignored.
<P>
<DT><TT>`symbol.lido'</TT>
<DD>A specification of the context conditions on uniqueness of set names and
elements within a single set.
<P>
<DT><TT>`code.fw'</TT>
<DD>A specification of the form of the output text and how it is constructed.
</DL>
<P>
File <TT>`sets.specs'</TT> lists the names of these four files and contains
requests to instantiate three library modules that support them.
<P>
<H3><A NAME="SEC9" HREF="novice_toc.html#SEC9">Exercises</A></H3>
<P>
Invoke Eli and type <KBD>?</KBD>, followed by a carriage return.
This request will begin a documentation browsing session.
Use the browser's <CODE>goto</CODE> command to place yourself at node
<CODE>(novice)tskex</CODE>
(Browser commands are described in
 <A HREF="info_2.html#SEC12">Some Advanced Info Commands of Info</A>.)
<P>
If you are using a computer with multiple-window capability, your
documentation browsing session is independent of your Eli session,
so you can simultaneously browse the documentation and make Eli requests.
Otherwise you must terminate the document browsing session in order to make
an Eli request.
In that case, you might want to make a note of your current node (given in
the highlighted status line) before exiting.
When you begin a new session, you can then use the <CODE>g</CODE> command to go
directly to that node.
<P>
<OL>
<LI>
Use the documentation browser's <CODE>run</CODE> command to obtain a copy of the
complete specification.
You will use this copy to do the exercises in the remainder of this
chapter.
<P>
<LI>
Verify that you have obtained all of the specification files by making the
following Unix request via Eli
(see  <A HREF="ui_4.html#SEC12">Running Unix commands from Eli of User Interface Reference Manual</A>):
<P>
<PRE>
-&#62; !ls
</PRE>
<P>
<LI>
Examine the file that is not a part of the specification by requesting Eli
to display it on screen
(see  <A HREF="ui_3.html#SEC10">Copying to Standard Output of User Interface Reference Manual</A>):
<P>
<PRE>
-&#62; input&#62;
</PRE>
</OL>
<P>
<H2><A NAME="SEC10" HREF="novice_toc.html#SEC10">Specifying the desired phrase structure</A></H2>
<P>
The first step in specifying a problem to Eli is to develop a
context-free grammar
<A NAME="IDX153"></A>
that describes the phrase structure
<A NAME="IDX154"></A>
of the input text.
This structure must reflect the desired semantics, and it must be possible
for Eli to construct a parser
<A NAME="IDX155"></A>
from the grammar.
Grammar development
<A NAME="IDX156"></A>
is a surprisingly difficult task.
It is best to concentrate on the meaning of the tree structure
<A NAME="IDX157"></A>
as you are developing the grammar,
and not try to economize by using the same symbols
to describe constructs that look the same but have different meanings.
<P>
One possible description of the structure of the set definition text is
(see  <A HREF="syntax_1.html#SEC2">How to describe a context-free grammar of Syntactic Analysis</A>):
<P>
<PRE>
text: set_defs .
set_defs: set_def / set_defs set_def .
set_def: set_name '{' set_body '}' .
set_name: word .
set_body: elements .
elements: set_element / elements set_element .
set_element: word .
</PRE>
<P>
Here each set definition is described as a <CODE>set_name</CODE> followed by a
bracketed <CODE>set_body</CODE>.
The text will be made up of an arbitrary number of such definitions.
A <CODE>set_body</CODE>, in turn, consists of an arbitrary number of elements.
The <CODE>set_name</CODE> and each <CODE>set_element</CODE> is a <CODE>word</CODE>.
<P>
This structure represents the semantics of the input text:
Set names and set elements have different meanings, even though they are
both written as words.
Set bodies are significant units, even though they have the same form as
any subset of themselves.
The following specification would <EM>not</EM> reflect the semantics, even
though it is simpler and describes the same input language:
<P>
<PRE>
text: set_defs .
set_defs: set_def / set_defs set_def .
set_def: word '{' elements '}' .
elements: word / elements word .
</PRE>
<P>
<H3><A NAME="SEC11" HREF="novice_toc.html#SEC11">Exercises</A></H3>
<P>
To get information about whether Eli can construct a parser from a grammar
without actually trying to build the whole program,
use the <CODE>:parsable</CODE>
<A NAME="IDX158"></A>
product
(see  <A HREF="pp_3.html#SEC27">parsable of Products and Parameters Reference Manual</A>).
In order to be parsable, the grammar must satisfy the
<DFN>LALR(1) condition</DFN>.
<A NAME="IDX159"></A>
If the LALR(1) condition is satisfied, <CODE>parsable</CODE> will indicate that
fact.
Otherwise it will say that the grammar is not LALR(1) and provide a listing
of conflicts
(see  <A HREF="syntax_3.html#SEC24">How to Resolve Parsing Conflicts of Syntactic Analysis</A>).
<P>
<OL>
<LI>
Tell Eli to explain what it is doing, and
request verification that Eli can generate a parser. Append <CODE>&#62;</CODE> to the 
derivation to tell Eli to copy the results on the screen.
<P>
<PRE>
-&#62; LogLevel=4
-&#62; sets.specs :parsable&#62;
</PRE>
<P>
When the process is complete, repeat the last request.
To save keystrokes, you can scroll through the <DFN>history</DFN>
<A NAME="IDX160"></A>
(see  <A HREF="ui_7.html#SEC19">The History Mechanism of User Interface</A>)
using the up- and down-arrow keys.
<P>
Explain the very different responses to the two requests
for verification of parsability.
<P>
<LI>
Request an editing session on the file <TT>`sets.con'</TT>
(see  <A HREF="ui_3.html#SEC11">Editing with the Copy Command of Eli User Interface Reference Manual</A>):
<A NAME="IDX162"></A>
<A NAME="IDX161"></A>
<P>
<PRE>
-&#62; sets.con&#60;
</PRE>
<P>
Delete <CODE>text</CODE> from the first rule of the grammar, leaving
the colon and everything following it unchanged.
Then request execution as before, scrolling through the history:
<P>
<PRE>
-&#62; sets.specs:parsable&#62;
</PRE>
<P>
Why was Eli's response so much shorter than before?
<P>
<LI>
Obtain help diagnosing the error you created by deleting <CODE>text</CODE>:
<A NAME="IDX163"></A>
<A NAME="IDX164"></A>
<P>
<PRE>
-&#62; sets.specs :parsable :help
</PRE>
<P>
This request will start a documentation browsing session.
<A NAME="IDX165"></A>
Follow the menu to the display for the file in error, and use the edit
command to gain access to that file.
Correct the error by inserting <CODE>text</CODE> before the colon,
exit the editor, and then quit the browsing session.
Use the Eli history mechanism to repeat the last request:
<P>
<PRE>
-&#62; sets.specs :parsable :help
</PRE>
<P>
Explain Eli's response to this request.
Why was no documentation browsing session started?
Why was the response so much shorter than the response to the original
request for derivation and execution of the processor?
<P>
<LI>
Your request for help after fixing the error really didn't demonstrate that
the grammar was parsable, because it didn't show you the result.
Request the result:
<P>
<PRE>
-&#62; sets.specs :parsable&#62;
</PRE>
<P>
Explain Eli's response to this request.
What steps were carried out to satisfy it?
Why were these the only ones necessary?
<P>
<LI>
Delete the braces { } from the rule defining <CODE>set_def</CODE> in file
<TT>`sets.con'</TT>.
This change makes the entire input text nothing but a list of words,
with no differentiation between set names and elements or between different
sets.
Eli will not be able to generate a parser from this grammar.
Request verification of parsability to see the error report:
<P>
<PRE>
-&#62; sets.specs :parsable &#62;
</PRE>
<P>
A <DFN>shift-reduce conflict</DFN>
<A NAME="IDX167"></A>
<A NAME="IDX166"></A>
is a situation in which the parser can't tell whether it should recognize a
complete phrase or continue to add symbols to an incomplete phrase.
In this example, the next word is either the name of a new set
(and thus the current <CODE>elements</CODE> phrase is complete), or 
it is another set element (and thus belongs to the current <CODE>elements</CODE>
phrase).
<P>
Add a comma as a separator between set elements, but do not re-introduce
the braces.
Do you think that Eli will be able to generate a parser?
Briefly explain, and then verify your answer.
(For a more complete treatment of conflict resolution, see
 <A HREF="syntax_3.html#SEC24">How to Resolve Parsing Conflicts of Syntactic Analysis</A>.)
<P>
Restore the original specification, or change <TT>`input'</TT> to conform to
your new specification, to ensure correct behavior for later exercises.
</OL>
<P>
<H2><A NAME="SEC12" HREF="novice_toc.html#SEC12">Nonliteral character sequences and comments</A></H2>
<P>
The terminal symbols
<A NAME="IDX168"></A>
of the grammar are the literal
<A NAME="IDX169"></A>
braces and the nonliteral symbol
<A NAME="IDX170"></A>
<CODE>word</CODE>.
Eli can easily deduce that the braces are significant characters, but we
must provide a definition of the significant character sequences
<A NAME="IDX171"></A>
that could make up a <CODE>word</CODE>.
We must also describe how to capture the significant information in a word
for further processing.
<P>
Eli normally assumes that white space
<A NAME="IDX172"></A>
characters (space, tab
<A NAME="IDX173"></A>
and newline)
<A NAME="IDX174"></A>
are not significant.
If we want to provide a facility for commenting a classification then we
must additionally define the form of a comment
<A NAME="IDX175"></A>
and specify that character sequences having this form are also not significant.
<P>
Here is one possible description of the non-literal character sequences
and comments:
<A NAME="IDX176"></A>
<A NAME="IDX177"></A>
<A NAME="IDX178"></A>
<P>
<PRE>
word:   $[a-zA-Z]+      [mkidn]
        C_COMMENT
</PRE>
<P>
The first line defines a <CODE>word</CODE> to be any sequence of one or more
letters
(see  <A HREF="lex_1.html#SEC2">Regular Expressions of Lexical Analysis</A>).
Whenever such a sequence is recognized in the input text, <CODE>mkidn</CODE> is
invoked to capture the significant information represented by the sequence.
This processor associates an integer with the recognized sequence, and
arranges for that integer to become the value representing the character
sequence.
If two character sequences recognized as words are identical, <CODE>mkidn</CODE>
will represent them with the same integer; distinct sequences are represented
by different integers.
<P>
The second line of the specification does not begin with a symbol followed
by <KBD>:</KBD>, which indicates that the character sequences it describes are
not significant.
It uses a <DFN>canned description</DFN>
<A NAME="IDX179"></A>
to describe character sequences taking the form of C comments
(see  <A HREF="lex_2.html#SEC13">Canned Symbol Descriptions of Lexical Analysis</A>).
Thus any character sequence taking the form of a C comment will be ignored
in the input text read by the generated program.
<P>
<H3><A NAME="SEC13" HREF="novice_toc.html#SEC13">Exercises</A></H3>
<P>
<OL>
<LI>
Tell Eli to keep quiet about what it is doing, and then ask it to run the
processor derived from your specification:
<A NAME="IDX180"></A>
<P>
<PRE>
-&#62; LogLevel=2
-&#62; input +cmd=(sets.specs :exe) :stdout &#62;
</PRE>
<P>
<LI>
The sample input file does not contain either comments or errors.
Introduce an error by inserting a digit into one of the words of the
example and repeat your request:
<P>
<PRE>
-&#62; input&#60;
-&#62; input +cmd=(sets.specs :exe) :stdout &#62;
</PRE>
<P>
Briefly explain Eli's response to this request.
<P>
<LI>
Verify that the generated processor correctly handles C comments.
<P>
<LI>
Change the specification to accept only words that begin with upper-case
letters.
Generate a translator and verify its correctness.
<P>
<LI>
Change the specification to allow Ada comments instead of C comments.
(Hint: see  <A HREF="lex_2.html#SEC13">Canned Symbol Descriptions of Lexical Analysis</A>.)
Generate a translator and verify its correctness.
</OL>
<P>
<H2><A NAME="SEC14" HREF="novice_toc.html#SEC14">Managing source text definitions</A></H2>
<P>
The statement of the problem requires that the names of the classes be
unique, and that there be only one occurrence of a given word in a given
class.
This sort of condition is very common in translation problems.
It involves recognition of regions
<A NAME="IDX181"></A>
and specific entities
<A NAME="IDX182"></A>
within those regions.
For example, a <CODE>set_body</CODE> is a region and a <CODE>set_element</CODE> is a
specific entity within that region.
The check to be made is that no <CODE>set_element</CODE> appears more than once
in any <CODE>set_body</CODE>.
<P>
Regions are defined by the grammar.
Entities may be defined both by the grammar and by the values representing
the terminal symbols: the grammar selects a particular kind of phrase,
while the instances of this phrase are differentiated by the values of their
terminal symbols.
Some computation must be carried out over the region to verify the
condition.
This computation is standard, involving only the concepts of region and
entity, so a <DFN>generic module</DFN>
<A NAME="IDX184"></A>
<A NAME="IDX183"></A>
can be used to carry it out.
<P>
In order to use a generic module
<A NAME="IDX185"></A>
we must instantiate that module and
connect the concepts it provides to the specification of our problem.
Instantiation
<A NAME="IDX186"></A>
is handled in the <TT>`sets.specs'</TT> file:
<P>
<PRE>
$/Name/AlgScope.gnrc :inst
$/Prop/Unique.gnrc :inst
</PRE>
<P>
The <CODE>AlgScope</CODE> module
<A NAME="IDX187"></A>
provides the concept of nested regions
<A NAME="IDX189"></A>
<A NAME="IDX188"></A>
containing entities distinguished by integer values
(see  <A HREF="name_2.html#SEC3">Algol-like Basic Scope Rules of Specification Module Library: Name Analysis</A>).
The <CODE>Unique</CODE> module
<A NAME="IDX190"></A>
provides the concept of an error for entities that
appear more than once in a region
(see  <A HREF="prop_4.html#SEC4">Check for Unique Object Occurrences of Specification Module Library: Properties of Definitions</A>).
<P>
An attribute grammar
<A NAME="IDX191"></A>
fragment is used to connect the concepts provided by
these two modules to the specification of the phrase structure:
<A NAME="IDX192"></A>
<A NAME="IDX193"></A>
<A NAME="IDX194"></A>
<P>
<PRE>
ATTR Sym: int;

SYMBOL Entity INHERITS IdDefScope, Unique COMPUTE
  SYNT.Sym=TERM;
  IF(NOT(THIS.Unique), 
     message(ERROR,"Multiply-defined word", 0, COORDREF));
END;

SYMBOL text INHERITS RootScope, RangeUnique END;
SYMBOL set_body INHERITS RangeScope END;
SYMBOL set_name INHERITS Entity END;
SYMBOL set_element INHERITS Entity END;
</PRE>
<P>
The symbol <CODE>Entity</CODE>,
<A NAME="IDX195"></A>
which does not occur in the context-free grammar, is used to represent the
concept of a word that must be unique within some region: a
<CODE>set_name</CODE> must be unique over the region lying outside of all sets,
while a <CODE>set_element</CODE> must be unique over the set in which it appears.
<CODE>Entity</CODE> allows us to gather all of the characteristics of that
concept in one place -- a <DFN>symbol attribution</DFN>
<A NAME="IDX196"></A>
-- and then use inheritance
<A NAME="IDX197"></A>
to associate those characteristics with the symbols that embody the concept.
<P>
An <CODE>Entity</CODE> appears in the input text as a word, which is represented
internally by the value representing the terminal symbol <CODE>word</CODE>.
That value was established by <CODE>mkidn</CODE> when the word was recognized
(see  <A HREF="novice_2.html#SEC12">Nonliteral character sequences and comments</A>).
<P>
The two symbols inheriting <CODE>Entity</CODE>, <CODE>set_name</CODE> and
<CODE>set_element</CODE>, are defined by rules that have terminal symbols on
their right-hand sides.
<CODE>TERM</CODE> can be used in a symbol computation to represent the value of
a terminal symbol appearing on the right-hand side of any rule defining the
given symbol
(see  <A HREF="lidoref_7.html#SEC11">Terminal Access of LIDO Reference Manual</A>).
Thus <CODE>SYNT.Sym=TERM</CODE> sets the <CODE>Sym</CODE> attribute of the
<CODE>Entity</CODE> to the value representing the terminal symbol defining that
<CODE>Entity</CODE>.
(<CODE>SYNT</CODE> means that the computation takes place in the
<DFN>lower context</DFN>
<A NAME="IDX199"></A>
<A NAME="IDX198"></A>
of the symbol, i.e. in the rules corresponding to the phrases
<CODE>set_name: word</CODE> and <CODE>set_element: word</CODE>.
See  <A HREF="lidoref_6.html#SEC8">Types and Classes of Attributes of LIDO Reference Manual</A>.)
<P>
The concept of a definition within a region is embodied in the symbol
<CODE>IdDefScope</CODE>
<A NAME="IDX200"></A>
exported by the <CODE>AlgScope</CODE> module, while the concept that such a
definition must be unique is embodied in the symbol <CODE>Unique</CODE>,
<A NAME="IDX201"></A>
exported by the <CODE>Unique</CODE> module.
Thus <CODE>Entity</CODE> inherits from these two symbols.
<P>
If the <CODE>Unique</CODE> attribute of the <CODE>Entity</CODE> is false,
then the <CODE>message</CODE>
<A NAME="IDX202"></A>
operation is invoked to output an error report. 
The report has severity
<A NAME="IDX204"></A>
<A NAME="IDX203"></A>
<CODE>ERROR</CODE>,
<A NAME="IDX205"></A>
which indicates that a definite error has been detected and therefore
no object code should be produced
(see  <A HREF="lib_1.html#SEC4">Source Text Coordinates and Error Reporting of Library Reference Manual</A>).
It is placed at the source text coordinates (line and column) represented
by <CODE>COORDREF</CODE>, and consists of the string
<CODE>Multiply-defined word</CODE>.
<CODE>COORDREF</CODE> always refers to the location of the leftmost character of
the phrase corresponding to the rule in which it appears.
Since this computation is inherited by <CODE>set_name</CODE> and
<CODE>set_element</CODE>, it appears in rules corresponding to the phrases
<CODE>set_name: word</CODE> and <CODE>set_element: word</CODE>.
Any error report will therefore refer to the leftmost character of the
multiply-defined word.
<P>
The <CODE>text</CODE> is the outermost region (<CODE>RootScope</CODE>),
<A NAME="IDX206"></A>
within which the set names are defined.
Each set body is an inner region (<CODE>RangeScope</CODE>),
<A NAME="IDX207"></A>
within which the set elements are defined.
Therefore <CODE>text</CODE> inherits the <CODE>RootScope</CODE> computations and
<CODE>set_body</CODE> inherits the <CODE>RangeScope</CODE> computations.
<P>
A <CODE>set_name</CODE> must be unique within the <CODE>text</CODE> and a
<CODE>set_element</CODE> must be unique within its <CODE>set_body</CODE>,
so both <CODE>text</CODE> inherits the <CODE>RangeUnique</CODE> computations.
<A NAME="IDX208"></A>
<P>
<H3><A NAME="SEC15" HREF="novice_toc.html#SEC15">Exercises</A></H3>
<P>
<OL>
<LI>
Create a subdirectory <TT>`src'</TT> and then request source code for the
set processor
(see  <A HREF="ui_4.html#SEC12">Running Unix commands from Eli of User Interface Reference Manual</A>):
<A NAME="IDX210"></A>
<A NAME="IDX209"></A>
<A NAME="IDX211"></A>
<P>
<PRE>
-&#62; !mkdir src
-&#62; sets.specs :source &#62;src
</PRE>
<P>
Does <TT>`src'</TT> <EM>really</EM> contain a version of the translator
that is independent of Eli?
How can you be certain?
<P>
<LI>
Try deriving source code without first creating a directory:
<P>
<PRE>
-&#62; sets.specs :source &#62;foo
</PRE>
<P>
What was the result?
Can you explain what happened?
<P>
<LI>
Request an executable version of the translator:
<P>
<PRE>
-&#62; sets.specs :exe &#62;sets.exe
</PRE>
<P>
Is this executable independent of Eli?
How can you be certain?
</OL>
<P>
<H2><A NAME="SEC16" HREF="novice_toc.html#SEC16">Creating structured output text</A></H2>
<P>
At least two specifications, and sometimes more, are needed to create
structured output text.
The form of the text must be described, along with the source of its
components.
Eli generates a set of procedures from the description of the form of the
text, one for each kind of component.
The information about the components is then provided by a computation that
invokes these procedures with appropriate arguments.
<P>
We have already seen how Eli allows us to break the specification into
files that encapsulate individual tasks.
So far, each of the tasks has required only one kind of specification.
Here, however, we have a single task that requires at least two
specifications.
There is strong coupling between these specifications, however, so that a
<A NAME="IDX212"></A>
change to one will often involve a change to the other.
The solution is to combine such related specifications
<A NAME="IDX213"></A>
into a single file of type <TT>`fw'</TT>.
<A NAME="IDX215"></A>
<A NAME="IDX214"></A>
A type-<TT>`fw'</TT> file describes a set of specification files that Eli will
separate as necessary, but which the user can manipulate as a single
entity.
<P>
The variable atoms of the generated C code are integers (like the number of
elements in a set) and strings (like the elements of a set).
<CODE>LeafPtg</CODE>
<A NAME="IDX216"></A>
(see  <A HREF="output_1.html#SEC1">PTG Output of Leaf Nodes of Specification Module Library: Generating Output</A>)
is a generic module
<A NAME="IDX217"></A>
that provides operations useful in writing such atoms,
so it is instantiated in file <TT>`sets.specs'</TT>:
<P>
<PRE>
$/Output/LeafPtg.gnrc :inst
</PRE>
<P>
Three related specifications are used to describe the creation of the C
declarations.
First the general form of the declarations is given in a special language
called <DFN>PTG</DFN>, then there is an attribute grammar
<A NAME="IDX218"></A>
fragment that computes
the individual components, and finally two C macros
<A NAME="IDX219"></A>
are needed to implement operations used in the computations.
All three specifications are combined in a single type-<TT>`fw'</TT> file
called <TT>`code.fw'</TT>:
<P>
<PRE>
@O@&#60;code.ptg@&#62;@{
Table:
  "int number_of_sets = " $/*integer*/ ";\n\n"
  "char *name_of_set[] = {\n"
  $/*list of set names*/ "};\n\n"
  "int size_of_set[] = {\n"
  $/*list of set sizes*/ "};\n\n"
  $/*list of sets*/
  "char **values_of_set[] = {\n"
  $/*list of set representations*/ "};"

Set:
  "char *set_of_" $/*set name*/ "[] = {\n"
  $/*list of set elements*/ "};\n\n"

Seq:
  $ $

List:
  $ ",\n" $

Quoted:
  "\"" $ "\""

Name:
  "set_of_" $
@}

@O@&#60;code.lido@&#62;@{
ATTR Ptg: PTGNode;
SYMBOL Entity INHERITS IdPtg END;

SYMBOL text COMPUTE
  IF(NoErrors,
    PTGOut(
      PTGTable(
        PTGNumb(CONSTITUENTS set_name.Sym WITH (int, ADD, ARGTOONE, ZERO)),
        CONSTITUENTS set_name.Ptg WITH (PTGNode, PTGList, PTGQuoted, PTGNull),
        CONSTITUENTS set_body.Size WITH (PTGNode, PTGList, PTGNumb, PTGNull),
        CONSTITUENTS set_def.Ptg WITH (PTGNode, PTGSeq, IDENTICAL, PTGNull),
        CONSTITUENTS set_name.Ptg WITH (PTGNode, PTGList, PTGName, PTGNull))));
END;

ATTR Size: int;
SYMBOL set_body COMPUTE
  SYNT.Size=CONSTITUENTS set_element.Sym WITH (int, ADD, ARGTOONE, ZERO);
END;

SYMBOL set_def COMPUTE
  SYNT.Ptg=
    PTGSet(
      CONSTITUENT set_name.Ptg,
      CONSTITUENTS set_element.Ptg WITH (PTGNode, PTGList, PTGQuoted, PTGNull));
END;
@}

@O@&#60;code.HEAD.phi@&#62;@{
#include "err.h"
#define NoErrors (ErrorCount[ERROR]==0)
@}
</PRE>
<P>
The PTG specification,
<A NAME="IDX220"></A>
which is introduced by <CODE>@O@&#60;code.ptg@&#62;@{</CODE> and
terminated by <CODE>@}</CODE>, is simply a collection of parameterized
templates
<A NAME="IDX221"></A>
for output.
Each template is given a name, and consists of a sequence of items that
will be output in the given order.
Quoted C strings are output as they stand, and each <KBD>$</KBD> stands for one
parameter.
A text fragment is constructed according to a particular template by
invoking a function whose name is <CODE>PTG</CODE> followed by the template name.
<A NAME="IDX222"></A>
This function returns a value of type <CODE>PTGNode</CODE>,
<A NAME="IDX223"></A>
and must be provided
with one argument of type <CODE>PTGNode</CODE> for each parameter.
<P>
To construct a text fragment according to the template named <CODE>Quoted</CODE>,
for example, invoke <CODE>PTGQuoted</CODE> with one argument of type
<CODE>PTGNode</CODE>.
The result will be a value of type <CODE>PTGNode</CODE> that describes the text
fragment <KBD>"</KBD>, followed by the text fragment described by the argument,
followed by <KBD>"</KBD>.
<P>
The attribute grammar fragment,
<A NAME="IDX224"></A>
which is introduced by
<CODE>@O@&#60;code.lido@&#62;@{</CODE> and terminated by <CODE>@}</CODE>,
invokes the PTG functions with appropriate arguments.
<CODE>PTGNumb</CODE>
<A NAME="IDX225"></A>
and <CODE>PTGName</CODE>
<A NAME="IDX226"></A>
are defined by the <CODE>LeafPtg</CODE>
<A NAME="IDX227"></A>
module
(see  <A HREF="output_1.html#SEC1">PTG Output of Leaf Nodes of Specification Module Library: Generating Output</A>).
They construct values of type <CODE>PTGNode</CODE> that describe the text
fragment consisting of a single integer value or word respectively.
These text fragments are then used in building larger text fragments, and
so on.
<P>
The translated output should be produced only if no errors were detected
by the translator.
<CODE>NoErrors</CODE> is a user-defined macro that tests whether any reports of
severity <CODE>ERROR</CODE>
<A NAME="IDX229"></A>
<A NAME="IDX230"></A>
<A NAME="IDX228"></A>
were issued.
<CODE>NoErrors</CODE> must be defined as a C macro, in a file of type
<TT>`.HEAD.phi'</TT>.
<A NAME="IDX232"></A>
<A NAME="IDX231"></A>
This can be done by a segment of the FunnelWeb file
introduced by <CODE>@O@&#60;code.HEAD.phi@&#62;@{</CODE> and terminated by <CODE>@}</CODE>.
<P>
The error module maintains an array <CODE>ErrorCount</CODE>,
<A NAME="IDX233"></A>
indexed by severity, each of whose elements specifies the number of reports
issued at the corresponding severity
(see  <A HREF="lib_1.html#SEC4">Source Text Coordinates and Error Reporting of Library Reference Manual</A>).
If the <CODE>ERROR</CODE> element of this array is <CODE>0</CODE>, then no reports
of severity <CODE>ERROR</CODE> have been issued.
<P>
In addition to building the C declarations, the attribute grammar fragment
computes the total number of sets and the total number of elements in each
set:
<A NAME="IDX234"></A>
<P>
<PRE>
ATTR Size: int;
SYMBOL set_body COMPUTE
  SYNT.Size=CONSTITUENTS set_element.Sym WITH (int, ADD, ARGTOONE, ZERO);
END;
</PRE>
<P>
<CODE>ADD</CODE>, <CODE>ARGTOONE</CODE> and <CODE>ZERO</CODE> are built-in functions of Eli
(see  <A HREF="lidoref_12.html#SEC21">Predefined Entities of LIDO Reference Manual</A>).
<P>
This computation visits nodes of the subtree rooted in the <CODE>set_body</CODE>
node.
If the node is a <CODE>set_element</CODE> node, function <CODE>ARGTOONE</CODE>
is applied to the value of the <CODE>Sym</CODE> attribute to yield the integer
value 1.
If the node has no <CODE>set_element</CODE> descendants, then its descendants are
not visited and the function <CODE>ZERO</CODE> is invoked with no arguments to
yield the integer value 0.
Otherwise the integers computed for the children of the node are combined
pairwise in left-to-right order via the function <CODE>ADD</CODE>.
See  <A HREF="lidoref_9.html#SEC16">CONSTITUENT(S) of LIDO Reference Manual</A>.
<P>
<H3><A NAME="SEC17" HREF="novice_toc.html#SEC17">Exercises</A></H3>
<P>
<OL>
<LI>
Request the code generated by the processor from the specification:
<A NAME="IDX235"></A>
<P>
<PRE>
-&#62; sets.specs :gencode :viewlist
</PRE>
<P>
Find the files generated from <CODE>code.fw</CODE> and verify the content of
<CODE>code.HEAD.phi</CODE>.
(Hint: Re-read the discussion of <CODE>code.fw</CODE>.)
<P>
<LI>
Which file contains the definition of the function <CODE>PTGQuoted</CODE>?
(Hint: Use grep, or create a <TT>`tags'</TT> file and then give the command
<CODE>vi -t PTGQuoted</CODE>.)
<P>
<LI>
Briefly explain the operation of <CODE>PTGQuoted</CODE>.
How is the text fragment created by this function printed?
<P>
<LI>
Use <CODE>lint</CODE>
<A NAME="IDX236"></A>
to search for anomalies in the collection of C routines.
Are any of those found significant?
Explain briefly.
<P>
<LI>
Request an interactive debugging session:
<A NAME="IDX238"></A>
<A NAME="IDX237"></A>
<A NAME="IDX239"></A>
<A NAME="IDX240"></A>
<P>
<PRE>
-&#62; sets.specs +debug :dbx
</PRE>
<P>
(If you prefer to use the GNU debugger gdb, simply replace
<A NAME="IDX241"></A>
<CODE>dbx</CODE> with <CODE>gdb</CODE>).
<P>
Set breakpoints to stop the program in <CODE>PTGQuoted</CODE>, <CODE>_PrPTGQuoted</CODE>
and <CODE>PTGOut</CODE>.
Run the program with the name of file <TT>`input'</TT> as its command line
argument.
What is the order of the calls to these three routines?
Explain briefly.
<P>
<LI>
Redefine the output text so that each array value is indented, and the
closing brace is at the beginning of a line.
For example, the array of set names should look like this:
<P>
<PRE>
char *name_of_set[] = {
        "colors",
        "bugs",
        "verbs"
};
</PRE>
<P>
Generate a translator and verify its correctness.
</OL>
<P>
<HR size=1 noshade width=600 align=left>
<P>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="novice_1.html"><IMG SRC="gifs/prev.gif" ALT="Previous Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="novice_3.html"><IMG SRC="gifs/next.gif" ALT="Next Chapter" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT=""><A HREF="novice_toc.html"><IMG SRC="gifs/up.gif" ALT="Table of Contents" BORDER="0"></A>
<IMG SRC="gifs/empty.gif" WIDTH=25 HEIGHT=25 ALT="">
<HR size=1 noshade width=600 align=left>
</TD>
</TR>
</TABLE>

</BODY></HTML>
